Skip to main content
Version: 5.3.0.0

Derby

title: Juno Mode Derby Database Security

An Orchestra operated in Juno mode is shipped with an integrated Derby database stored in the local file system.

Derby Standard Security​

The database runs in the default Derby security mode, which does not require database authentication. Orchestra utilizes the database in embedded mode, meaning that the database is opened within the Orchestra process itself, eliminating the need for public network endpoints. This configuration ensures that network access is not possible.

Improved Security​

An attacker with direct access to the local file system may read the content and open the databases. If this scenario is not acceptable, an improved security mode can be configured. This mode enforces password authentication for the entire database, even if the system is copied. To activate this mode, follow these instructions:

Open the Orchestra Derby database with the ij-command line tool (see ij_intro.html).

Execute the following commands after replacing the placeholders with parameters specific to your database:

  • <path-to-derby-database-directory>: Absolute path to your database directory
  • <password>: Password for authentication

Step 1:

ij> connect 'jdbc:derby:<path-to-derby-database-directory>';
ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.ORCHESTRAUSER', '<password>');
ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.connection.requireAuthentication', 'true');
ij> disconnect;

Step 2:

Change the value of the database password parameter (database.runtime.pwd) in environment_settings.xml of the Juno installation to the password you just set. Encrypt the password with the password tool provided by Orchestra.

Also, change the value of the database user parameter (database.runtime.user) in environment_settings.xml to ORCHESTRAUSER, and encrypt the username with the password tool provided by Orchestra.

Encrypted Derby Database with Auto Install​

If an attacker gains direct access to the local file system, they may read the content and open the databases. To address this, an improved security mode can be established, where the Derby database is set up in encrypted mode. In this configuration, all database files are encrypted using an initial boot password.

Details can be found here: develop115.html.

warning

The described installation steps can only be used to create a Juno database from scratch. The procedure cannot be applied to an existing database.

Open the Orchestra Derby database with the ij-command line tool (see ij_intro.html).

Execute the following commands after replacing the placeholders with parameters specific to your database:

  • <path-to-derby-database-directory>: Absolute path to your database directory
  • <password>: Password for authentication
  • <bootpassword>: Password for encrypting the database

Step 1 - Create an initial Derby database in encrypted mode:

ij> connect 'jdbc:derby:<path-to-derby-database-directory>;create=true;dataEncryption=true;bootPassword=<bootpassword>';
ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.ORCHESTRAUSER', '<password>');
ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.connection.requireAuthentication', 'true');
ij> disconnect;

Step 2 - Configure Orchestra Properly:

  • Change the value of the database password parameter (database.runtime.pwd) in environment_settings.xml to the password you just set. Encrypt the password with the password tool provided by Orchestra.

  • Change the value of the database user parameter (database.runtime.user) in environment_settings.xml to ORCHESTRAUSER. Encrypt the username with the password tool provided by Orchestra.

  • Set the value of the auto install flag (database.auto.install) to true to ensure the database is created automatically during Orchestra startup.

    <parameter name="auto.install" value="true"/>

  • Change the value of the database URL parameter (database.runtime.url) in environment_settings.xml. The URL has the following format:

    jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword=ThisIsTheBootPassword

    • If the bootPassword is given literally, the format is:

      jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword=ThisIsTheBootPassword

    • If the bootPassword is given via an operating system variable, the format is:

      jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword={system.<NameOfOsVariable>}

    • If the bootPassword is provided as a Java command line parameter, the format is:

      jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword={property.<NameOfProperty>}

Encrypted Derby Database with Flyway​

If an attacker has direct access to the local file system, they may read the content and open the databases. If this scenario is not acceptable, an improved security mode can be established. This section describes how to set up the Derby database in encrypted mode, where all database files are encrypted using an initial boot password.

Details can be found here: develop115.html.

warning
  • The described installation steps can only be used to create a Juno database from scratch, meaning they cannot be applied to an existing database.
  • The Flyway approach can be used to create a Juno database independent of Orchestra.

The basic approach is described under Flyway DB Migration and Versioning.

Please replace the following placeholders with parameters specific to your database:

  • <path-to-derby-database-directory>: Absolute path to your database directory
  • <password>: Password for authentication
  • <bootpassword>: Password for encrypting the database

Step 1 - Create an initial Derby database that runs in encrypted mode:

Adapt your Flyway configuration file as follows:

flyway.url=jdbc:derby:<path-to-derby-database-directory>;create=true;dataEncryption=true;bootPassword=<bootpassword>
flyway.password=<password>
flyway.user=ORCHESTRAUSER
flyway.locations=filesystem:../Derby

Step 2 - Enable Password Authentication for the Created Database:

Open the Orchestra Derby database with the ij-command line tool and execute these commands:

ij> connect 'jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword=<bootpassword>';
ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.user.ORCHESTRAUSER', '<password>');
ij> CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY('derby.connection.requireAuthentication', 'true');
ij> disconnect;

Step 3 - Configure Orchestra Properly:

  • Change the value of the database password parameter (database.runtime.pwd) in environment_settings.xml to the password you set. Encrypt the password with the password tool provided by Orchestra.

  • Change the value of the database user parameter (database.runtime.user) in environment_settings.xml to ORCHESTRAUSER. Encrypt the username with the password tool provided by Orchestra.

  • Change the value of the database URL parameter (database.runtime.url) in environment_settings.xml. The given URL format is:

    jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword=<bootpassword>;

    • If the bootPassword is supplied in plain text, the format is:

      jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword=ThisIsTheBootPassword

    • If the bootPassword is provided by an operating system variable, the format is:

      jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword={system.<NameOfOsVariable>}

    • If the bootPassword is given as a Java command line parameter, the format is:

      jdbc:derby:<path-to-derby-database-directory>;dataEncryption=true;bootPassword={property.<NameOfProperty>}